Phantom allows developers to trace and breakpoint PowerTalk Template code resource calls (to the code resource) and call-backs (to the Catalogs Extension). Phantom was developed as an internal test tool to aide in the quality assurance process. However, it can be very useful when developing PowerTalk Templates which include code resources.
Phantom is being provided to developers strictly "as is," with no support or promises of future expansion or bug fixes. Not all of it works. What does work has a less-than-perfect user interface. In short, if you don't like it, don't use it. But don't complain to us.
How to use Phantom
------------------
Most of Phantom's menus are unused (including even the Quit command in the File menu).
You use the Phantom menu to start things up and to quit. You use the Calls menu to set traces and breakpoints on calls from the Catalogs Extension to the template code resource. You use the CallBacks menu to set traces and breakpoints on call-backs from the code resource to the Directories Extension.
Phantom menu:
Phantom recording is automatically enabled at startup, you should not need to use the Startup Events submenu of the Phantom menu. (This sends an AppleEvent to the Directories Extension telling it to start reporting calls and call-backs to Phantom.) Finder Tracking should be checked. When you're done using Phantom, simply select the Quit command from the Phantom menu. The Directories Extension will automatically notice that Phantom is no longer running and stop trying to send information to it.
Calls menu:
Choosing "Show Window" from the Calls menu opens a window that lists all the calls. You can display data before the call or after the call. You can display minimum data (what call is being made to what template) or all the data (the complete call block). (But if you display all data, it isn't actually •all• the data.)
You can also break before or after the call. The before breakpoint is in the CE before calling your code rsrc—you will need to step over the StripAddress call, and then into the subsequent call, and you'll soon be in your code resource. You can then put a breakpoint in your code, or just step through it. The after breakpoint isn't very useful for debugging templates (but it's sure nice for debugging the CE).
Display and breakpoint options are set by selecting one or more items in the window, and then using the Calls menu. As a short-cut, you can type the following letters when the Calls window is open:
Letter Effect
------ ------
b Display before
a Display after
m Display minimum data
< Breakpoint before
> Breakpoint after
option-b Don't display before
option-a Don't display after
option-m Display as much data as possible
option-< Don't breakpoint before
option-> Don't breakpoint after
command-a select all
When you set these options (via the Calls menu or by typing letters), letters will show up in the window to the left of the call. The letters displayed are the same as those shown above for type-in short-cuts. Capital letters mean maximum data, small letters mean minimum data. By default, everything except Idle, DynamicResource, ShouldSync, DoSync, PropertyDirtied is on.
If you open an info page or your Personal Catalog or use anything that calls a template code resource, data will be displayed in the Phantom Output window.
CallBacks menu:
Call-backs are displayed and breakpointed in exactly the same way. The Show Window command in the CallBacks menu displays a second window listing all of the call-backs. This window works in exactly the same way as the Calls window. Options are set for the window using commands in the CallBacks menu. The same type-in selection short-cuts are available as well.
The default for the CallBacks window is everything turned off.
Other menus:
You can choose the New command from the File menu to create a new output window. Phantom will direct output to the frontmost window. You then have this nifty file that you can save for bedtime reading or open in MacWrite (or whatever) and print.
The Clear command in the Edit menu allows you to clear the Phantom Output window.
Another useful feature is Silent Mode. The "Preferences..." command in the Settings menu will bring up a dialog box with many checkboxes. The only one Phantom observes is "Silent Mode". This is useful if you have just done something which generated a lot of output that you realize you don't want, so instead of waiting for Phantom to spit it all out, you can turn on "Silent Mode" and Phantom will empty its buffer more quickly without cluttering up your output window.
Tips & Caveats
--------------
• Phantom buffers all of the information it displays until the Phantom process gets time. Then it displays everything at once. There are two consequences of this that you need to be aware of: (1) It's possible to lose data because of buffer overflow. When this happens, the system will drop momentarily into Macsbug with an "out of interrupt memory" assert. And (2) The fact that Phantom hasn't yet displayed a call or call-back (especially if you're stopped in a breakpoint in the CE or your code resource), doesn't mean it hasn't happened yet. It may be in the buffer waiting to be displayed.
• You shouldn't assume that because you notice a particular call being made by the CE at a particular time or in a particular pattern that it will always happen that way. We may change the CE at some point in the future, and a template that depends on how it behaves today may no longer work.
• Don't turn all display on and open an info-page with more that 1 address in a sublist or anything that complex. Phantom generates a lot of output—it must save this output between WaitNextEvent calls. If it generates too much output, it will assert "out of interrupt memory; g" or something close to that, which means you have lost data. It will also slooow you down. In general, I keep all display off, except for the one or three calls and callbacks that I am debugging. I'd advise doing the same.
If you must generate all that output, try to call kDETcmdBusy from within your code rsrc, this should give Phantom a chance to empty its buffer.
• If you are looking at calls or callbacks from or to attribute aspects (in sublists), the name that Phantom displays is the name of the parent, not the name of the attribute.
• If you display anything with a pointer or a handle, Phantom may crash if the thing is undefined. Even if the parameter is defined to be undefined. So be careful what you display, only display parameters that will be valid. For example, display GetPropertyRString AFTER the callback not before.
This tool is provided as part of the AOCE SDK. Use of this tool for any purpose other than the development of AOCE-based Macintosh® products is a violation of the license agreement covering this SDK.
